Feat: Outline import #1478

NicolasRitouet · 2025-10-12T15:02:52Z

Purpose

Add Outline import functionality to allow users to migrate their documentation from Outline by uploading a .zip export file.

Proposal

Add backend API endpoint to handle Outline .zip upload
- Implement Outline export processing service that:
  - Extracts markdown files from the archive
  - Converts markdown content to BlockNote format (Yjs)
  - Preserves document hierarchy and nested documents
  - Handles image attachments by uploading them to object storage
- Add frontend import page at /import/outline
- Fix CSRF token handling in upload request
- Prevent duplicate documents for nested structures (e.g., Doc.md + Doc/ directory)
- Add French translations for the import UI

External contributions

Thank you for your contribution! 🎉

Please ensure the following items are checked before submitting your pull request:

I have read and followed the contributing guidelines
I have read and agreed to the Code of Conduct
I have signed off my commits with git commit --signoff (DCO compliance)
I have signed my commits with my SSH or GPG key (git commit -S)
My commit messages follow the required format: <gitmoji>(type) title description
I have added a changelog entry under ## [Unreleased] section (if noticeable change)
I have added corresponding tests for new features or bug fixes (if applicable)

…kend:\n- Add POST /api/v1.0/outline_import/upload (zip)\n- Parse .md files, create doc tree from folders, rewrite image links to attachments, convert to Yjs via Y-provider\nFrontend:\n- Add /import/outline page with zip file picker + POST\n- Add menu entry 'Import from Outline' in left panel header\n- Add minimal i18n keys (en, fr)

…ous forbidden\n- Authenticated happy path with local image and mocked conversion

…import.py and call from view\n- Keep view thin; service handles zip, images, conversion, attachments\n- Fix imports accordingly

…ject unsafe paths)\n- Ignore __MACOSX and hidden entries\n- Service unit tests (happy path + zip slip)\n- Change API path to /imports/outline/upload and update front + tests

…kNote elements - Convert H4/H5/H6 headings to compatible formats (H4→H3 with marker, H5→bold with arrow, H6→paragraph with bullet) - Convert horizontal rules (---, ***, ___) to [DIVIDER_BLOCK] markers - Preserve task lists formatting for proper checkbox rendering - Add comprehensive unit tests for all conversion cases This ensures Outline exports with all 6 heading levels and other markdown features are properly imported into BlockNote.js which only supports 3 heading levels.

…ted BlockNote elements" This reverts commit b7a7663.

Resolved conflict in translations.json by keeping Outline import translations

- Add CSRF token to Outline import upload request - Fix content save by removing invalid update_fields parameter - Handle nested documents properly to avoid duplicates when a document has child documents (e.g., Doc.md with Doc/ directory)

NicolasRitouet · 2025-10-12T15:13:38Z

In progress:

UI is ugly
attachments are not uploaded
not all content blocks have been tested

StephanMeijer · 2025-10-29T10:31:31Z

src/backend/core/services/outline_import.py

+
+def _upload_attachment(user, doc: models.Document, arcname: str, data: bytes) -> str:
+    """Upload a binary asset into object storage and return its public media URL."""
+    content_type, _ = mimetypes.guess_type(arcname)


What is the library underneath using? Mimetype guessing is not always stable (even when using libmagic it can differ from version/environment).
I would suggest good testing, preferably in different environments if possible.

StephanMeijer · 2025-10-29T10:32:57Z

src/backend/core/services/outline_import.py

+        parts = [p for p in name.split("/") if p]
+        if any(part == ".." for part in parts):
+            raise OutlineImportError("Unsafe path in archive")


Is this always unsafe or only when .. goes beyond the root you are iterating over?

lunika · 2025-11-10T10:18:04Z

src/backend/core/api/imports.py

+        uploaded = request.FILES.get("file")
+        if not uploaded:
+            raise drf.exceptions.ValidationError({"file": "File is required"})
+
+        name = getattr(uploaded, "name", "")
+        if not name.endswith(".zip"):
+            raise drf.exceptions.ValidationError({"file": "Must be a .zip file"})


You should rely on a drf serializer here to validate the input instead of doing it in the view. You can maybe reused the FileUploadSerializer present in the serializer module (src/backend/core/api/serializers.py)

Then once the input validated you have to rely on the malware_detection feature to validate the zip content. But we have to imagine a workflow, this process is async. Once the malware detection ended, the process_outile_zip should start.

lunika · 2025-11-10T10:19:47Z

src/backend/core/api/imports.py

+            # Fail fast if the upload is not a valid zip archive
+            with zipfile.ZipFile(io.BytesIO(content)):
+                pass
+            created_ids = process_outline_zip(request.user, content)


I suggestion to save the uploaded zip on the bucket storage (you can rely on the django storage API). Doing this you can create a celery task to process the file in an async way

lunika · 2025-11-10T10:20:45Z

src/backend/core/services/outline_import.py

+    return f"{settings.MEDIA_BASE_URL}{settings.MEDIA_URL}{key}"
+
+
+def process_outline_zip(user, zip_bytes: bytes) -> list[str]:


With the previous comment made, asking to save the file on the bucket, you can transform this function in a celery task and execute it asynchronously

lunika · 2025-11-10T10:30:05Z

src/backend/core/services/outline_import.py

+        models.DocumentAccess.objects.update_or_create(
+            document=doc,
+            user=user,
+            defaults={"role": models.RoleChoices.OWNER},
+        )


Suggested change

models.DocumentAccess.objects.update_or_create(

document=doc,

user=user,

defaults={"role": models.RoleChoices.OWNER},

)

You have to define an owner access for the user only on the root document. Then the children will inherit from this access.

lunika · 2025-11-10T10:31:03Z

src/backend/core/services/outline_import.py

+                creator=user,
+                title=part,
+                link_reach=models.LinkReachChoices.RESTRICTED,
+            )


Suggested change

)

)

models.DocumentAccess.objects.create(

document=doc,

user=user,

role=models.RoleChoices.OWNER,

)

lunika · 2025-11-10T10:32:05Z

src/backend/core/services/outline_import.py

+        if parent_doc is None:
+            doc = models.Document.add_root(
+                depth=1,
+                creator=user,
+                title=title,
+                link_reach=models.LinkReachChoices.RESTRICTED,
+            )
+        else:
+            doc = parent_doc.add_child(creator=user, title=title)


Suggested change

if parent_doc is None:

doc = models.Document.add_root(

depth=1,

creator=user,

title=title,

link_reach=models.LinkReachChoices.RESTRICTED,

)

else:

doc = parent_doc.add_child(creator=user, title=title)

This is managed in _ensure_dir_documents function. You will probably have duplicated docs at the end

lunika · 2025-11-10T10:32:20Z

src/backend/core/services/outline_import.py

+        models.DocumentAccess.objects.update_or_create(
+            document=doc,
+            user=user,
+            defaults={"role": models.RoleChoices.OWNER},
+        )


Suggested change

models.DocumentAccess.objects.update_or_create(

document=doc,

user=user,

defaults={"role": models.RoleChoices.OWNER},

)

Managed in the _ensure_dir_documents function

lunika · 2025-11-10T10:38:55Z

src/backend/core/services/outline_import.py

+    extra_args = {
+        "Metadata": {
+            "owner": str(user.id),
+            "status": enums.DocumentAttachmentStatus.READY,


Suggested change

"status": enums.DocumentAttachmentStatus.READY,

"status": enums.DocumentAttachmentStatus.PROCESSING,

NicolasRitouet added 13 commits September 13, 2025 07:28

frontend(import-outline): fix baseApiUrl import path

1fd4406

outline-import: run malware scan on uploaded assets

becc514

tests(outline-import): add API tests for upload (.zip) flow\n- Anonym…

9f4fb06

…ous forbidden\n- Authenticated happy path with local image and mocked conversion

refactor(outline-import): move import logic to core/services/outline_…

4f3b62d

…import.py and call from view\n- Keep view thin; service handles zip, images, conversion, attachments\n- Fix imports accordingly

outline-import: reinforce safety and tests\n- Zip Slip protection (re…

fa65c45

…ject unsafe paths)\n- Ignore __MACOSX and hidden entries\n- Service unit tests (happy path + zip slip)\n- Change API path to /imports/outline/upload and update front + tests

Add Outline import API view

cce6c96

Remove legacy Outline import viewset

6146a48

Improve Outline import validation and UI

453b153

Revert "feat(outline-import): Add markdown preprocessing for unsuppor…

06d9c2b

…ted BlockNote elements" This reverts commit b7a7663.

Merge main into feature/outline-import

95fa210

Resolved conflict in translations.json by keeping Outline import translations

NicolasRitouet marked this pull request as draft October 12, 2025 15:03

NicolasRitouet added 3 commits October 12, 2025 17:18

Cleanup imports

538c641

Fix import outline

619b624

add new line

e1f5a13

NicolasRitouet changed the title ~~Feature/outline import~~ Feat: Outline import Oct 12, 2025

es-lint fixes

7d6f055

virgile-dev requested review from lunika and rl-83 October 13, 2025 08:57

virgile-dev mentioned this pull request Oct 15, 2025

Import outline notes into docs #1471

Open

StephanMeijer reviewed Oct 29, 2025

View reviewed changes

lunika reviewed Nov 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat: Outline import #1478

Feat: Outline import #1478

NicolasRitouet commented Oct 12, 2025 •

edited

Loading

Uh oh!

NicolasRitouet commented Oct 12, 2025

Uh oh!

StephanMeijer Oct 29, 2025 •

edited

Loading

Uh oh!

StephanMeijer Oct 29, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

lunika Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		return f"{settings.MEDIA_BASE_URL}{settings.MEDIA_URL}{key}"


		def process_outline_zip(user, zip_bytes: bytes) -> list[str]:

	"status": enums.DocumentAttachmentStatus.READY,
	"status": enums.DocumentAttachmentStatus.PROCESSING,

Feat: Outline import #1478

Are you sure you want to change the base?

Feat: Outline import #1478

Conversation

NicolasRitouet commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

Proposal

External contributions

Uh oh!

NicolasRitouet commented Oct 12, 2025

Uh oh!

StephanMeijer Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

NicolasRitouet commented Oct 12, 2025 •

edited

Loading

StephanMeijer Oct 29, 2025 •

edited

Loading